From b7f08d6531f02d33e69be6b8206a659042fcd40e Mon Sep 17 00:00:00 2001 From: Wendell Smith Date: Fri, 19 Jun 2015 09:15:37 -0400 Subject: [PATCH] Return guide and manifest to original format, but with additional info This puts the main "Project Layout" section back into `manifest.md` as it was before, but adds a bit more detail to that section both those pages and a link between them. --- src/doc/guide.md | 44 ++++++++++---------------------------------- src/doc/manifest.md | 37 +++++++++++++++++++++++++++++++------ 2 files changed, 41 insertions(+), 40 deletions(-) diff --git a/src/doc/guide.md b/src/doc/guide.md index 9e9f5cc55..b3743a64b 100644 --- a/src/doc/guide.md +++ b/src/doc/guide.md @@ -202,43 +202,19 @@ we choose to `cargo update` again. # Project Layout Cargo uses conventions for file placement to make it easy to dive into a new -Cargo project. +Cargo project. Here the conventions that Cargo uses: -`Cargo.toml` is kept in the root directory, as is `Cargo.lock`. +* `Cargo.toml` and `Cargo.lock` are stored in the root of your project. +* Source code goes in the `src` directory. +* The default library file is `src/lib.rs`. +* The default executable file is `src/main.rs`. +* Other executables can be placed in `src/bin/*.rs`. +* External tests go in the `tests` directory. +* Example executable files go in the `examples` directory. +* Benchmarks go in the `examples` directory. -If your project is an executable, name the main source file `src/main.rs`. If it -is a library, name the main source file `src/lib.rs`. Cargo can create either of -these automatically with `cargo new --bin` or `cargo new`. - -## Optional Components - - * `src/bin/`: Other executables, to be built by default with - `cargo build` - * `examples/`: Examples of usage, built with `cargo test` or `cargo build - --example NAME` - * `tests/`: Integration tests, built and run with `cargo test` - * `benches/`: Benchmarks, built and run with `cargo bench` - These are explained in more detail in the [manifest -description](manifest.html#examples), but for now, here is an example directory -layout: - -```notrust -Cargo.toml -Cargo.lock -▾ src/ # directory containing source files - lib.rs # the main entry point for libraries and packages - main.rs # the default file for a project producing an executable - *.rs # other modules - ▾ bin/ # (optional) directory containing executables - *.rs -▾ examples/ # (optional) examples of library usage - *.rs -▾ tests/ # (optional) integration tests - *.rs -▾ benches/ # (optional) benchmarks - *.rs -``` +description](manifest.html#the-project-layout). # Cargo.toml vs Cargo.lock diff --git a/src/doc/manifest.md b/src/doc/manifest.md index 4f3746800..f948991c7 100644 --- a/src/doc/manifest.md +++ b/src/doc/manifest.md @@ -365,16 +365,41 @@ tests and benchmarks. These dependencies are *not* propagated to other packages which depend on this package. +# The Project Layout + +If your project is an executable, name the main source file `src/main.rs`. +If it is a library, name the main source file `src/lib.rs`. + +Cargo will also treat any files located in `src/bin/*.rs` as +executables. + +Your project can optionally contain folders named `examples`, `tests`, and +`benches`, which Cargo will treat as containing example executable files, +integration tests, and benchmarks respectively. + +```notrust +▾ src/ # directory containing source files + lib.rs # the main entry point for libraries and packages + main.rs # the main entry point for projects producing executables + ▾ bin/ # (optional) directory containing additional executables + *.rs +▾ examples/ # (optional) examples + *.rs +▾ tests/ # (optional) integration tests + *.rs +▾ benches/ # (optional) benchmarks + *.rs +``` + # Examples -Files located under `examples` are example uses of the functionality provided by -the library (see [the guide](guide.html#project-layout) for a further -description of standard project layout). When compiled, they are placed in the +Files located under `examples` are example uses of the functionality +provided by the library. When compiled, they are placed in the `target/examples` directory. -They must compile as executables (with `main.rs`) and load in the -library by using `extern crate `. They are compiled when -you run your tests to protect them from bitrotting. +They must compile as executables (with a `main()` function) and load in the +library by using `extern crate `. They are compiled when you run +your tests to protect them from bitrotting. # Tests -- 2.30.2